home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Just Call Me Internet
/
Just Call Me Internet.iso
/
prog
/
atari
/
m2
/
cat3src
/
cat
/
doku
/
catproto.txt
next >
Wrap
Text File
|
1997-10-26
|
10KB
|
246 lines
Dokumentation zum erweiterten CAT-Messageprotokoll (29.04.96)
CAT kann mit einem Watchdog ber ein eigenes Protokoll kommunizieren.
Dieses Protokoll wurde zur Version 2.0 von CAT um einiges erweitert,
was aber nie komplett dokumentiert wurde. Dieses Dokument soll diese
Lcke schlieen.
Die gesamte Kommunikation luft ber eine AES-Nachricht ab, die
Unterscheidung der einzelnen Anforderungen wird dabei ber Sub-Opcodes
erledigt, die im Messagebuffer abgelegt werden. Es gilt folgender
grundlegener Aufbau des AES-Messagebuffers:
mess[0] = 0x8000; (* CatMsg *)
mess[1] = apId; (* Die von CAT bzw. dem Kommunikationspartner *)
mess[2] = oversize; (* immer 0 *)
mess[3] = Sub-Opcode; (* Siehe Tabelle *)
mess[4-7]: Message-spezifische Daten
Folgende Sub-Opcodes sind definiert:
(* Sub-Opcodes fr CatMsg *)
enableWatchDog = 0;
disableWatchDog = 1;
CatAffirm = 2;
CatAsk = 3;
CatAccept = 4;
CatForget = 5;
CatGreetings = 6;
CatTerminate = 7;
CatFiltered = 8;
(* Sub-Opcodes fr das erweiterte Protokoll: *)
WdwManager = 9;
CatWinInfo = 10;
CatWhatsIn = 11;
CatPosition = 12;
CatNewMess = 13;
CatInform = 14; (* nicht implementiert *)
CatWinDirty = 15; (* nicht implementiert *)
CatProtoVersion = 1; (* Das ist Version Nummer 1 *)
Die Sub-Opcodes haben dabei folgende Bedeutung:
msg[3] msg[4]
CatGreetings
6 0 CB->Cat Anmeldung bei Cat (evtl. kommt in mess[5] noch eine
Unterscheidung, ob es sich um einen WatchDog handelt, also
dort am besten eine Null eintragen). Fr etwas anderes als
einen Watchdog darf in mess[5] keine 0 stehen.
6 version Cat-CB Anmeldung angekommen, Protokoll-Versionsnummer zum
berprfen als Anlage.
WdwManager
9 art ACC->Cat, Anforderung der offenen Fenster, mess[5+6]
enthalten eine Adresse fr den Buffer, in den CAT
die Information hineinschreibt. mess[7] enthlt die
Maximalanzahl an Fenstern, die in den Buffer passen
(pro Eintrag ein Integer, also 2 Byte)
"art" enthlt die Art der Fenster, die geliefert
werden sollen: 0: MsgFenster, 1: Editoren, 2:
Stichwortlisten
Aktuell ist nur die Anforderung der Information ber
die MsgFenster mglich, mehr ist nicht implementiert.
9 art Cat->ACC, offene Fenster, mess[5+6] enthlt den Pointer
auf den Buffer, der vorher bergeben wurde. In dem Buffer
steht die Liste der Fensterhandles, wenn das vom AES aus
klappt. mess[7] enthlt die Anzahl der Fenster, die von
CAT geliefert werden.
CatWinInfo
10 whdl ACC->Cat, Informationen anfordern. mess[5+6] enhlt eine
Adresse, die sagt, wo die Informationen sollen , Format der
Information wie "winInfo" (siehe unten). mess[7]
enthlt die Lnge des Buffers in mess[5+6].
Achtung: Das eine Wort kann dazu evtl. nicht ausreichen!
10 whdl Cat->ACC, Information wurde geschrieben, Bufferadresse
wieder in mess[5+6], Lnge in 7 (unverndert).
Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse
und die Lnge auf 0.
CatWhatsIn
11 whdl CB->Cat, Welche Informationen werden im angegebenen Fenster
dargestellt? mess[5+6] enthlt einen Zeiger auf folgende
Struktur:
RECORD
gruppe: CARDINAL; (* Gruppennummer, 0 = Privat *)
num : CARDINAL; (* interne Nachrichtenummer, 0-65534 *)
size : LONGCARD; (* Anzahl Bytes fr alle Informationen,
* die man mit CatWinInfo anfordern kann
*)
END;
11 whdl Cat->CB mess[5+6] enthlt wieder den Zeiger auf obige
Struktur
Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse
auf 0.
CatPosition
12 whdl CB->Cat, Informationen ber MsgPositionen. mess[7] gibt an,
um welche Art es sich handelt: 0 Neue, 1 letzte Position, 2
ab Datum, 3 ab Nummer. In den letzten beiden Fllen wird in
mess[5+6] noch eine Adresse auf einen String bergeben, der
das Datum bzw. die ID enthlt. Er ist nullterminiert.
12 whdl Cat->CB, mess[5] interne Msgenummer; 0xffff heit: Nicht
gefunden
CatNewMess
13 whdl CB->Cat, neuen Inhalt setzen: mess[5] Gruppe mess[6] interne
MsgNummer
13 whdl Cat->CB mess[5] = 0 -> hat geklappt, mess[5] # 0 -> geht
nich..
Zu der Funktion CatWinInfo ist eine nhere Erluterung unumgnglich.
Insbesondere kann es passieren, da das eine Wort in dem Buffer nicht
ausreicht fr die Gesamtanzahl der Bytes! Daher gilt zustzlich folgendes:
Wenn die per CatWhatsIn erfragte Gre nicht in ein Wort pat
(d.h. > 65535 ist), dann ist der zu allozierende Buffer um 4 Byte zu
vergrern und das erste Langwort in diesem Buffer gibt dann die Gre
des allozierten Buffers ohne diese 4 Byte an. In der Nachricht ist in msg[7]
dann eine 0 zu bergeben!
CAT gibt genau diesen Buffer auch wieder zurck, d.h. auch in dem
zurckgegebenen Buffer enthalten die ersten 4 Bytes ein Langwort mit der
Gesamtlnge.
Was steht nun in diesem Buffer, nachdem CAT ihn gefllt hat? Einiges! CAT
fllt den Buffer mit der internen Nachrichtenstruktur, mit allen Headertexten
und mit dem kompletten Nachrichtentext (wenn denn der Buffer gro genug ist).
Das sieht dann so aus:
Nachrichtenstruktur
Infotexte (* an nchster gerader Adresse, ggf. Fllbyte davor *)
Nachrichtentext (* an nchster gerader Adresse, ggf. Fllbyte davor *)
Die Struktur am Anfang des Blocks ist folgende:
MessageType = RECORD
MailNr, (* interne Nachrichtennummer *)
MailAnz : CARDINAL; (* Anzahl der Nachrichten in der Gruppe *)
KommentierteID : String255; (* Referenz-Id (256 Bytes) *)
fromOther : BOOLEAN; (* Wurde die ID von der anderen Msg gelesen? *)
MailID,
Betreff,
Absender,
Empfaenger,
mid,
rid,
box,
gate,
mime,
name : Str255Ptr; (* zeigen auf Positionen in "InfoStrings" *)
Gruppe : CARDINAL; (* Interne Gruppennummer *)
Datum,
StatusDatum (* nur persnliche *)
: DateType;
infoLen : CARDINAL; (* letztes Byte in <InfoStrings> *)
textLen : CARDINAL; (* letztes Byte im <Text> *)
StatusBits : BITSET; (* siehe unten *)
up,
down,
left,
right : CARDINAL; (* interne Nummern der verknpften Nachrichten *)
KommentarAnzahl
: CARDINAL;
statusDate : LONGCARD; (* Bei persnlichen: Statusdatum im MT-Format *)
tauschDate : LONGCARD; (* Datum im MausTauschformat *)
EigeneNachricht : BOOLEAN;
Status : CHAR;
Text,
InfoStrings : BigTextPtr; (* Zeiger auf Speicherblcke *)
distribution : tDistribution; (* Distribution der Nachricht *)
END;
Folgende Typen werden dabei verwendet:
TYPE tDistribution = (dNone, dLokal, dMausNet, dNet);
DateType = ARRAY[0..18] OF CHAR; (* Datum aus der Datenbank,
* fertig formatiert als Text
*)
String255 = ARRAY[0..255] OF CHAR;
Str255Ptr = POINTER TO String255;
BigText = ARRAY[0..MAX(CARDINAL)] OF CHAR;
BigTextPtr = POINTER TO BigText;
Die Statusbits sind wie folgt definiert:
(* Statusbits einer Msg *)
CONST bGelesen = 0;
bFiltered = 1;
bInteressant = 2;
bTeilloeschung = 3;
bTotalloeschung = 4;
bKommentieren = 5;
bAntworten = 6;
bUser1 = 7;
bUser2 = 8;
bVererben = 9;
bComToOwnMessage = 10;
bOwnMessage = 14;
bOldComToOwnMessage = 13;
(* da einige Betaversionen das so hatten, wird in einer bergangsphase beides *)
(* erkannt und ggf. 13 entfernt und dafr 10 gesetzt *)
(* Vorlufig bis bei der Maus die Message-Ids diesen Namen auch verdienen: *)
bOldDupe = 15;
Auerdem steht oben noch so etwas dubioses wie "Bei persnlichen:
Statusdatum im MT-Format", und das bei einem LONGCARD, dabei wei doch
jeder, da das Datum im MausTausch ein String ist. Mit dieser
Formulierung ist folgende Codierung gemeint:
(* Maus-Datumsstring in ein Cat-Datum umwandeln *)
Ein Maustausch-Datum hat folgendes Format:
Jahr|Jahr|Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute
Von dem Jahr wird nun 1990 abgezogen und das ganze in eine Zahl in folgendem
Format gewandelt:
Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute
Aus einem Text "199604292210" wird somit die Zahl 0604292210.
Sekundenangaben im Maustauschformat werden hierbei nicht verarbeitet.
Und noch eine Erluterung, und zwar zum Feld "fromOther". In diesem Feld
steht nur dann TRUE, wenn CAT beim Lesen der Nachricht die ID der kommentierten
Nachricht schon aus dieser gelesen hat. Dies wird nur dann ausgefhrt, wenn die
ID nicht im Header enthalten ist, d.h. kann eigentlich gar nicht mehr auftreten.
Fr externe Programme ist dieses Feld auch uninteressant, da die ID entweder
in der Struktur vorhanden ist oder leer ist.